.TH gerbv 1 "Jule 13, 2013" Version @version@
.SH NAME
gerbv - Gerber Viewer
.SH SYNOPSIS
.B gerbv [OPTIONS]  [gerberfile[s]]
.SH DESCRIPTION
.PP
\fIgerbv\fP is a viewer for RS274-X, commonly known as Gerber, files.
RS274-X files are generated from different PCB CAD programs and are
used in the printed circuit board manufacturing process.
\fIgerbv\fP also supports Excellon/NC drill files as well as XY (centroid)
files produced by the program PCB (http://pcb.geda-project.org/).

.SH OPTIONS

.B Warning! 
On some platforms, which hasn't long option available, only
short options are available.

.SS gerbv General options:
.BI -V|--version
Print the version number of gerbv and exit.
.TP
.BI -h|--help
Print a brief usage guide and exit.
.TP
.BI -b<hex>|--background=<hex>
Use background color <hex>. <hex> is specified as an html-color code, 
e.g. #FF0000 for Red.
.TP
.BI -f<hex>|--foreground=<hex>
Use foreground color <hex>. <hex> is specified as an html-color code, 
e.g. #00FF00 for Green. If a user also wants to set the alpha (rendering 
with Cairo) it can be specified as an #RRGGBBAA code. Use multiple 
\-f flags to set the color for multiple layers.
.TP
.BI -l\ <filename>|--log=<filename>
All error messages etc are stored in a file with filename \fI<filename>\fP.
.TP
.BI -t\ <filename>|--tools=<filename>
Read Excellon tools from the file \fI<filename>\fP.
.TP
.BI -p\ <project\ filename>|--project=<project\ filename>
Load a stored project. Please note that the project file must be stored in
the same directory as the Gerber files.

.SS gerbv Export-specific options:
The following commands can be used in combination with the \-x flag:
.TP
.BI -B<b>|--border=<b>
Set the border around the image <b> percent of the width and height. 
Default <b> is 5%.
.TP
.BI -D<XxY>or<R>|--dpi=<XxY>or<R>
Resolution (Dots per inch) for the output bitmap. Use <XxY> for different 
resolutions for the width and height (only when compiled with Cairo as 
render engine). Use <R> to have the same resolution in both directions.
Defaults to 72 DPI in both directions.
.TP
.BI -T<XxYrR|X;YrR>|--translate=<XxYrR|X;YrR>
Translate image by X and Y and rotate by R degree. Use multiple \-T flags to
translate multiple files. Distance defaults to inches but may be changed with
\-\-units.  Only evaluated when exporting as RS274X or drill.
.TP
.BI -O<XxY|X;Y>|--origin=<XxY|X;Y>
Set the lower left corner of the exported image to coordinate <XxY>.
Coordinates defaults to inches but may be changed with --units.
.TP
.BI -a|--antialias
Use antialiasing for the generated output-bitmap.
.TP
.BI -o\ <filename>|--output=<filename>
Export to <filename>. 
.TP
.BI -u<inch/mm/mil>|--units=<inch/mm/mil>
Use given unit for coordinates. Default to inches.
.TP
.BI -W<WxH>|--window_inch=<WxH>
Window size in inches <WxH> for the exported image.
.TP
.BI -w<WxH>|--window=WxH>
Window size in pixels <WxH> for the  exported image. Autoscales to 
fit if no resolution is specified (note that the default 72 DPI also 
changes in that case). If a resolution is specified, it will clip 
the image to this size.
.TP
.BI -x<png/pdf/ps/svg/rs274x/drill>|--export=<png/pdf/ps/svg/rs274x/drill>   
Export to a file and set the format for the output file.

.SS GTK Options
.BI --gtk-module= MODULE
Load an additional GTK module
.TP
.BI --g-fatal-warnings
Make all warnings fatal
.TP
.BI --gtk-debug= FLAGS
GTK debugging flags to set
.TP
.BI --gtk-no-debug= FLAGS
GTK debugging flags to unset
.TP
.BI --gdk-debug= FLAGS
GDK debugging flags to set
.TP
.BI --gdk-no-debug= FLAGS
GDK debugging flags to unset
.TP
.BI --display= DISPLAY
X display to use
.TP
.BI --sync
Make X call synchronous
.TP
.BI --no-xshm
Don't use X shared memory extension
.TP
.BI --name= NAME
Program name as used by the window manager
.TP
.BI --class= CLASS
Program class as used by the window manager

.SH GENERAL
When you start gerbv you can give the files to be loaded on the command line,
either as each file separated with a space or by using wildcards.

The user interface is graphical. Simply press and drag middle mouse button
(scroll wheel) and the image will pan as you move the mouse. To manipulate a
layer, right-click on one of the rightmost list items. That will bring up a
pop-up menu where you can select what you want to do with that layer (reload
file, change color, etc).

If you hold the mouse button over one the rightmost button a tooltips will
show you the name of the file loaded on that layer.

.SH ACTIVATION AND DEACTIVATION OF LAYERS
You can load several files at one time. You can then turn displaying of the
layers on and off by clicking on one of check boxes near the layer names.

You can also control this from the keyboard. Press Ctrl, enter the number
on the layer you want activate/deactivate on the numerical keypad and then
release the Ctrl key.

.SH ALIGNING OF LAYERS
You can align two layers by selected elements. Select one element on each of
two layers and click Align layers from context menu.

.SH ZOOMING
Zooming can be handled by either menu choices, keypressing or mouse scroll
wheel. If you press z you will zoom in and if you press Shift+z (i.e. Z) you
will zoom out. Scroll wheel works if you enabled that in your X server and
mapped it to button 4 and 5. You can make the image fit by pressing f (there is
also a menu alternative for this). If Pan, Zoom, or Measure Tool is selected
you can press right mouse button for zoom in, and if you press Shift and right
mouse button you will zoom out.

You can also do zooming by outline. Select Zoom Tool, press mouse button, draw,
release. The dashed line shows how the zooming will be dependent on the
resolution of the window. The non-dashed outline will show what you actually
selected. If you change your mind when started to mark outline, you can always
abort by pressing escape. By holding down the Shift key when you press the
mouse button, you will select an area where the point you started at will be
the center of your selection.

.SH MEASUREMENTS
You can do measurement on the image displayed. Select Measure Tool, the cursor
changes to a plus. By using left mouse button you can draw the lines that you
want to measure. The result of the last measurement is also displayed on the
statusbar. All measurements are in the drawing until you select other Tool.
To measure distance between elements select two of them and switch to Measure
Tool.

The statusbar shows the current mouse position on the layer in the same 
coordinates as in the file. I.e. if you have (0,0) in the middle of the image
in the Gerber files, the statusbar will show (0,0) at the same place.

.SH SUPERIMPOSING
When you load several Gerber files, you can display them "on top of each other",
i.e. superimposing. The general way to display them are that upper layers
cover the layers beneath, which is called copy (GTK+ terms).

The other ways selectable are and, or, xor and invert. They map directly to
corresponding functions in GTK. In GTK they are described as:
"For colored images, only GDK_COPY, GDK_XOR and GDK_INVERT are generally 
useful. For bitmaps, GDK_AND and GDK_OR are also useful."

.SH PROJECTS
gerbv can also handle projects. A project consist of bunch of 
loaded layers with their resp. color and the background color. The easiest
way to create a project is to load all files you want into the layer
you want, set all the colors etc and do a "Save Project As...".

You load a project either from the menu bar or by using the commandline 
switches \-p or \-\-project.

Currently there is a limit in that the project file must be in the same
directory as the Gerber files to be loaded.

.SH SCHEME
The project files are simple Scheme programs that is interpreted by a
built in Scheme interpreter. The Scheme interpreter is TinyScheme and
needs a Scheme program called init.scm to initialize itself. The search
path for init.scm is (in the following order) 
@scmdir@, the directory with the executable
gerbv, the directory gerbv was invoked from and finally
according to the environment variable GERBV_SCHEMEINIT.

.SH "TOOLS FILE"
Not every Excellon drill file is self-sufficient. Some CADs produce .drd
files where tools are only referenced, but never defined (such as what
diameter of the tool is.) Eagle CAD is one of such CADs, and there are more
since many board houses require Tools files.

A Tools file is a plain text file which you create in an editor. Each line
of the file describes one tool (the name and the diameter, in inches):

.nf
	T01 0.024
	T02 0.040
	...
.fi

These are the same tools (T01 etc.) that are used in the Drill file.
A standard practice with Eagle is to create an empty Tools file, run the
CAM processor, and the error report tells you which tools you "forgot".
Then you put these tools into the file and rerun the CAM processor.

You load a tool file by using the commandline switches \-t or \-\-tools.
The file can have any name you wish, but Eagle expects the file type to
be ".drl", so it makes sense to keep it this way. Some board houses are
still using CAM software from DOS era, so you may want to exercise caution
before going beyond the 8.3 naming convention.

When \fIgerbv\fP reads the Tools file it also checks that there are no
duplicate definitions of tools. This does happen from time to time as you
edit the file by hand, especially if you, during design, add or remove parts
from the board and then have to add new tools into the Tools file. The
duplicate tools are a very serious error which will stop (HOLD) your board
until you fix the Tools file and maybe the Excellon file. \fIgerbv\fP will
detect duplicate tools if they are present, and will exit immediately to
indicate such a fatal error in a very obvious way. A message will also be
printed to standard error.

If your Excellon file does not contain tool definitions then \fIgerbv\fP
will preconfigure the tools by deriving the diameter of the drill bit
from the tool number. This is probably not what you want, and you
will see warnings printed on the console.

.SH PICK&PLACE FILE
Supported comma separated file (CSV) with fixed order of data:

.nf
	# X,Y in mils.
	Designator,"Description","Value",X,Y,"Rotation (deg)",top/bottom

	or

	Designator,"Footprint","Mid X","Mid Y","Ref X","Ref Y",
			"Pad X","Pad Y",T/B,"Rotation","Comment"
.fi

Units can be specified in format "# X,Y in mils." or as suffix for
X/Y-coordinates, i.e ",10mil,". Supported units: in, mil, cmil, dmil, km, m,
dm, cm, mm, um, nm.

.SH "ENVIRONMENT"
.IP GERBV_SCHEMEINIT
Defines where the init.scm file is stored. Used by scheme interpreter, which 
is used by the project reader.

.SH "AUTHOR"
.nf
Stefan Petersen (spetm at users.sourceforge.net): Overall hacker and project leader
Andreas Andersson (e92_aan at e.kth.se): Drill file support and general hacking
Anders Eriksson (aenfaldor at users.sourceforge.net): X and GTK+ ideas and hacking

.SH COPYRIGHT
.nf
Copyright \(co  2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Stefan Petersen

This document can be freely redistributed according to the terms of the 
GNU General Public License version 2.0
